home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / LOCK_ALLOC.z / LOCK_ALLOC
Encoding:
Text File  |  2002-10-03  |  7.4 KB  |  133 lines
  1.  
  2.  
  3.  
  4. LLLLOOOOCCCCKKKK____AAAALLLLLLLLOOOOCCCC((((DDDD3333))))                                                  LLLLOOOOCCCCKKKK____AAAALLLLLLLLOOOOCCCC((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _LLLL_OOOO_CCCC_KKKK______AAAA_LLLL_LLLL_OOOO_CCCC, _LLLL_OOOO_CCCC_KKKK______IIII_NNNN_IIII_TTTT - basic lock initialization
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ttttyyyyppppeeeessss....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////kkkkmmmmeeeemmmm....hhhh>>>>
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////kkkkssssyyyynnnncccchhhh....hhhh>>>>
  15.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ddddddddiiii....hhhh>>>>
  16.  
  17.      lllloooocccckkkk____tttt ****LLLLOOOOCCCCKKKK____AAAALLLLLLLLOOOOCCCC((((uuuucccchhhhaaaarrrr____tttt _h_i_e_r_a_r_c_h_y,,,, ppppllll____tttt _m_i_n__p_l,,,,
  18.           llllkkkkiiiinnnnffffoooo____tttt ****_l_k_i_n_f_o_p,,,, iiiinnnntttt _f_l_a_g))));;;;
  19.  
  20.      vvvvooooiiiidddd LLLLOOOOCCCCKKKK____IIIINNNNIIIITTTT((((lllloooocccckkkk____tttt ****_l_o_c_k_p,,,, uuuucccchhhhaaaarrrr____tttt _h_i_e_r_a_r_c_h_y,,,, ppppllll____tttt _m_i_n__p_l,,,,
  21.           llllkkkkiiiinnnnffffoooo____tttt ****_l_k_i_n_f_o_p))));;;;
  22.  
  23.    AAAArrrrgggguuuummmmeeeennnnttttssss
  24.      _h_i_e_r_a_r_c_h_y Set to -1.  Reserved for future use.
  25.  
  26.      _m_i_n__p_l    Minimum priority level argument which asserts the minimum
  27.                priority level that will be passed in with any attempt to
  28.                acquire this lock [see _LLLL_OOOO_CCCC_KKKK(D3)].
  29.  
  30.      _l_k_i_n_f_o_p   Set to -1.  Reserved for future use.
  31.  
  32.      _f_l_a_g      Specifies whether the caller is willing to sleep waiting for
  33.                memory.
  34.  
  35. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  36.      LOCK_ALLOC dynamically allocates and initializes an instance of a basic
  37.      lock.  LOCK_INIT initializes an already-allocated instance of a basic
  38.      lock.  The lock is initialized to the unlocked state.
  39.  
  40.      If _f_l_a_g is set to KM_SLEEP, the caller will sleep if necessary until
  41.      sufficient memory is available.  If _f_l_a_g is set to KM_NOSLEEP, the caller
  42.      will not sleep, but LOCK_ALLOC will return NULL if sufficient memory is
  43.      not immediately available.
  44.  
  45.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  46.      Upon successful completion, LOCK_ALLOC returns a pointer to the newly
  47.      allocated lock.  If KM_NOSLEEP is specified and sufficient memory is not
  48.      immediately available, LOCK_ALLOC returns a NULL pointer.
  49.  
  50.    mmmmiiiinnnn____ppppllll AAAArrrrgggguuuummmmeeeennnntttt
  51.      The valid values for this argument are as follows:
  52.  
  53.           _pppp_llll_bbbb_aaaa_ssss_eeee         Block no interrupts
  54.  
  55.           _pppp_llll_tttt_iiii_mmmm_eeee_oooo_uuuu_tttt      Block functions scheduled by itimeout and dtimeout
  56.  
  57.           _pppp_llll_dddd_iiii_ssss_kkkk         Block disk device interrupts
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. LLLLOOOOCCCCKKKK____AAAALLLLLLLLOOOOCCCC((((DDDD3333))))                                                  LLLLOOOOCCCCKKKK____AAAALLLLLLLLOOOOCCCC((((DDDD3333))))
  71.  
  72.  
  73.  
  74.           _pppp_llll_ssss_tttt_rrrr          Block STREAMS interrupts
  75.  
  76.           _pppp_llll_hhhh_iiii           Block all interrupts
  77.  
  78.      The notion of a _m_i_n__p_l assumes a defined order of priority levels.  The
  79.      following partial order is defined:
  80.  
  81.      _pppp_llll_bbbb_aaaa_ssss_eeee _<<<< _pppp_llll_tttt_iiii_mmmm_eeee_oooo_uuuu_tttt _<<<<_==== _pppp_llll_dddd_iiii_ssss_kkkk_,,,,_pppp_llll_ssss_tttt_rrrr _<<<<_==== _pppp_llll_hhhh_iiii
  82.  
  83.      The ordering of _pppp_llll_dddd_iiii_ssss_kkkk and _pppp_llll_ssss_tttt_rrrr relative to each other is not defined.
  84.  
  85.      Setting a given priority level will block interrupts associated with that
  86.      level as well as any levels that are defined to be less than or equal to
  87.      the specified level.  In order to be portable a driver should not acquire
  88.      locks at different priority levels where the relative order of those
  89.      priority levels is not defined above.
  90.  
  91.      The _m_i_n__p_l argument should specify a priority level that would be
  92.      sufficient to block out any interrupt handler that might attempt to
  93.      acquire this lock.  In addition, potential deadlock problems involving
  94.      multiple locks should be considered when defining the _m_i_n__p_l value.  For
  95.      example, if the normal order of acquisition of locks A and B (as defined
  96.      by the lock hierarchy) is to acquire A first and then B, lock B should
  97.      never be acquired at a priority level less than the _m_i_n__p_l for lock A.
  98.      Therefore, the _m_i_n__p_l for lock B should be greater than or equal to the
  99.      _m_i_n__p_l for lock A.
  100.  
  101.      Note that the specification of _m_i_n__p_l with a _LLLL_OOOO_CCCC_KKKK______AAAA_LLLL_LLLL_OOOO_CCCC call does not
  102.      actually cause any interrupts to be blocked upon lock acquisition, it
  103.      simply asserts that subsequent _LLLL_OOOO_CCCC_KKKK calls to acquire this lock will pass
  104.      in a priority level at least as great as _m_i_n__p_l.
  105.  
  106.    LLLLeeeevvvveeeellll
  107.      Base.
  108.  
  109.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  110.      May sleep if flag is set to _KKKK_MMMM______SSSS_LLLL_EEEE_EEEE_PPPP (_LLLL_OOOO_CCCC_KKKK______AAAA_LLLL_LLLL_OOOO_CCCC only) or if debugging
  111.      locks are installed.
  112.  
  113.      Driver-defined basic locks and read/write locks may not be held across
  114.      calls to this functions.
  115.  
  116.      Driver-defined sleep locks may be held across calls to this function
  117.      regardless of the value of _f_l_a_g.
  118.  
  119. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  120.      LOCK(D3), LOCK_DEALLOC(D3), LOCK_DESTROY(D3), TRYLOCK(D3), UNLOCK(D3).
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.